APM Review Panel: ship_with_followups

Default-on drift detection is a strong positioning move; ship after adding the recovery hint and syncing stale docs -- zero blockers, clean severity discipline.

The panel converged cleanly: zero blocking findings across eight specialists, strong approval of the replay-engine architecture, and consistent praise for the read-only/cache-only safety boundary. The highest-signal finding came from two independent personas (cli-logging-expert AND devx-ux-expert) identifying the same gap: drift output tells users WHAT drifted but never HOW to fix it. This violates APM's 'Include the fix' messaging rule and npm-audit's precedent. A one-line append ('Run: apm install') is a trivial fix that should land in this PR before merge -- it's the difference between a diagnostic and a product.

The supply-chain-security-expert raised a legitimate concern: replay trusts cache content without verifying it matches lockfile resolved_commit. The current defense (NotImplementedError on network replay + cache populated only by prior verified installs) is pragmatic for v1, but shared CI caches and mounted volumes are a real threat vector. This warrants a tracked follow-up issue, not a gate. The test-coverage-expert's missing inverse-normalization test (outcome: missing, unit tier) is worth noting: the safety invariant 'normalization does NOT mask real drift' has no automated guard. This is a regression-trap gap on a secure-by-default surface -- elevate above opinion-tier nits.

Doc-sync debt is the other consistent theme: cli-commands.md, ci-cd.md (still recommending the bash workaround this PR supersedes), and quick-start.md all need updates. The doc-writer and devx-ux-expert converge here. These are cheap fixes that should land in-PR to avoid shipping a feature whose docs contradict themselves on day one.

Dissent. No substantive dissent. Python-architect's scratch_root seam concern and supply-chain's atexit fragility point at the same underlying trade-off (temp-dir lifecycle); both agree it's recommended-tier, not blocking. Auth-expert correctly self-deactivated -- no auth surface touched.

Aligned with: secure-by-default (default-on, cache-only, no credential surface), governed-by-policy (SARIF + --ci exit code), portable-by-manifest (lockfile resolved_commit as source of truth), pragmatic-as-npm (one command, zero config, opt-out via --no-drift).

Growth signal. Drift detection opens a new pillar under 'lockfile-grade reproducibility'. The launch beat writes itself: 'apm audit catches what your CI bash script misses.' Before/after story (4 lines of fragile bash vs. one command with SARIF for free) is strong social-thread material. Ensure cross-links land so the guide isn't an orphan page with zero internal-link equity.

Panel summary

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

1. [DevX UX Expert] Add recovery hint to drift output: 'Run: apm install' after each drift group -- Two-persona convergence (cli-logging + devx-ux). Violates 'Include the fix' rule. One-line fix that converts a diagnostic into a product moment. Should land in-PR.
2. [Doc Writer] Update cli-commands.md (--no-drift flag), ci-cd.md (remove obsolete bash workaround), and quick-start.md (stale cross-ref) -- Three stale doc surfaces contradict the new behavior. Shipping without sync means day-one user confusion. Cheap fixes, same PR.
3. [Supply Chain Security Expert] Track follow-up issue: verify cache content matches lockfile resolved_commit before replay trusts it -- Shared CI caches and mounted volumes are a real poisoning vector. Current defense (prior-install trust) is pragmatic for v1 but the integrity primitive (commit-SHA pinning) is bypassed at replay time.
4. [Test Coverage Expert] Add inverse-normalization unit test asserting real content drift is NOT suppressed by BOM/CRLF/Build-ID guards -- Evidence outcome=missing on a secure-by-default safety invariant. A normalization bug could silently mask real drift with no automated guard catching the regression.
5. [OSS Growth Hacker] Add inbound cross-links from ci-policy-setup, governance-guide, and making-the-case to the new drift-detection guide -- Guide currently has zero internal-link equity -- it's discoverable only via sidebar. Cross-links from high-traffic pages drive adoption of the new capability.

Architecture

classDiagram
    direction LR
    class ReplayConfig {
        <<ValueObject>>
        +project_root Path
        +lockfile_path Path
        +targets frozenset~str~ | None
        +cache_only bool
    }
    class DriftFinding {
        <<ValueObject>>
        +path str
        +kind str
        +package str
        +inline_diff str
    }
    class CacheMissError {
        <<Exception>>
    }
    class CheckLogger {
        <<Base+Subclass>>
        +replay_start()
        +diff_start()
        +replay_complete(n)
        +clean()
        +findings(n)
    }
    class CommandLogger {
        <<Base>>
        +verbose bool
        +error(msg)
        +warning(msg)
        +success(msg)
    }
    class _ReadOnlyProjectGuard {
        <<ContextManager>>
        +project_root Path
        +protected_roots list~Path~
        +__enter__()
        +__exit__()
    }
    class ProtectedPathMutationError {
        <<Exception>>
    }
    class DiagnosticCollector {
        <<Collect-then-render>>
        +drift(msg, path)
        +drift_count int
    }
    class integrate_package_primitives {
        <<IOBoundary>>
        +scratch_root Path | None
    }
    CheckLogger --|> CommandLogger : extends
    _ReadOnlyProjectGuard ..> ProtectedPathMutationError : raises
    class ReplayConfig:::touched
    class DriftFinding:::touched
    class CacheMissError:::touched
    class CheckLogger:::touched
    class _ReadOnlyProjectGuard:::touched
    class ProtectedPathMutationError:::touched
    class integrate_package_primitives:::touched
    classDef touched fill:#fff3b0,stroke:#d47600

flowchart TD
    A["apm audit (commands/audit.py)"] --> B{--ci flag?}
    B -- yes --> C["_audit_ci_gate()"]
    B -- no --> D["_audit_content_scan()"]
    C --> E{"--no-drift?"}
    D --> F{"--no-drift AND no --file/--strip/--package?"}
    E -- no --> G["[NET] _check_drift(project_root, lockfile)"]
    F -- no --> G
    E -- yes --> H["skip drift, warn on stderr"]
    F -- yes --> H
    G --> I["run_replay(ReplayConfig, CheckLogger)"]
    I --> J["[FS] _make_scratch_root() tempfile.mkdtemp + atexit"]
    J --> K["_assert_scratch_bound(project, scratch)"]
    K --> L{"for lock_dep in lockfile"}
    L --> M["[FS] _materialize_install_path() resolve cache path"]
    M --> N["_build_package_info() loads apm.yml if present"]
    N --> O["[FS] integrate_package_primitives(scratch_root=scratch_root)"]
    O --> P["[FS] ensure_path_within(project_root, scratch_root)"]
    P --> L
    L -- done --> Q["diff_scratch_against_project()"]
    Q --> R["[FS] _walk_managed(scratch, governed_roots)"]
    Q --> S["[FS] _walk_managed(project, governed_roots)"]
    R --> T["_normalize() on each file pair (BOM + CRLF + Build-ID strip)"]
    S --> T
    T --> U["emit list~DriftFinding~"]
    U --> V{"format?"}
    V -- text --> W["render_drift_text()"]
    V -- json --> X["render_drift_json()"]
    V -- sarif --> Y["render_drift_sarif()"]

sequenceDiagram
    participant User
    participant AuditCmd as commands/audit.py
    participant CIChecks as policy/ci_checks.py
    participant Drift as install/drift.py
    participant Services as install/services.py
    participant FS as Filesystem

    User->>AuditCmd: apm audit [--ci]
    AuditCmd->>CIChecks: _check_drift(project_root, lockfile)
    CIChecks->>Drift: run_replay(ReplayConfig, CheckLogger)
    Drift->>FS: mkdtemp (scratch dir)
    Drift->>Drift: _assert_scratch_bound(project, scratch)
    loop each locked dependency
        Drift->>FS: _materialize_install_path (cache lookup)
        Drift->>Services: integrate_package_primitives(scratch_root=scratch)
        Services->>Services: ensure_path_within(project_root, scratch_root)
        Services->>FS: write primitives to scratch
    end
    CIChecks->>Drift: diff_scratch_against_project(scratch, project, lockfile)
    Drift->>FS: _walk_managed(scratch) + _walk_managed(project)
    Drift->>Drift: _normalize() each pair
    Drift-->>CIChecks: list[DriftFinding]
    CIChecks-->>AuditCmd: (CheckResult, findings)
    AuditCmd->>User: render_drift(findings, format)

Recommendation

Land the recovery hint and doc-sync fixes in this PR (both are trivial, same-day work), then merge. Track cache-integrity verification and inverse-normalization test as follow-up issues. The feature is architecturally sound, the test suite is strong (43 new tests), and the positioning value is high. No reason to delay beyond the in-PR polish pass.

_{This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.}

Addressed in-PR (commit 7907865)

Per the CEO panel recommendation, landed the two convergent in-PR follow-ups:

1. Recovery hint (cli-logging + devx-ux):
render_drift_text now appends [i] Run 'apm install' to re-sync deployed files with the lockfile. -- the diagnostic now tells users WHAT drifted AND HOW to fix it in one message. Honors Message Writing Rule #4 ('Include the fix').

2. Doc-sync (doc-writer + devx-ux):

• reference/cli-commands.md -- added --no-drift to audit options; amended --ci to mention drift contribution.
• integrations/ci-cd.md -- replaced the now-superseded bash git status --porcelain workaround with apm audit --ci; updated 'We dogfood this' callout.
• getting-started/quick-start.md -- retargeted stale cross-ref to the new drift-detection guide.
• guides/drift-detection.md -- removed the self-contradictory case Integrate copilot runtime #2 in 'When to use --no-drift' (strip-mode is auto-skipped, not opt-out).
• CHANGELOG.md -- compressed to one Keep-a-Changelog line pointing readers to the guide.

All 45 drift tests pass; lint clean.

Tracked as follow-up issues (CEO call)

• supply-chain-security: verify cache content matches lockfile resolved_commit before drift replay trusts it (commit-SHA pinning bypass on shared CI caches with mounted volumes). Will file as a separate issue.
• test-coverage: inverse-normalization unit test asserting BOM/CRLF/Build-ID guards do NOT mask real content drift (safety invariant on a secure-by-default surface). Will file as a separate issue.
• growth: inbound cross-links from ci-policy-setup, governance-guide, making-the-case to the drift-detection guide (internal-link equity). Cheap follow-up PR.
• architecture: scratch_root kwarg formalization as a DeployTarget protocol; lift normalization helpers to utils/normalization.py for sharing with compile/verify pipelines.
• logging: TTY/--quiet awareness in CheckLogger; verbose scratch-path disclosure.

Status

PR is ready for review. CEO stance: ship_with_followups.

Follow-ups landed (3 commits on top of feat/drift-detection)

Addressed every Copilot inline review comment plus the panel-deferred follow-ups (supply-chain hardening, growth surface, additional test coverage, logging refinement) in the same PR.

Commit map

Cache-pin marker contract (B1, supply-chain follow-up)

apm install drops a .apm-pin JSON marker ({schema_version: 1, resolved_commit: <sha>}) into each cached package root. apm audit verifies it before drift replay. Catches the two real-world hazards the panel called out:

1. Teammate bumps apm.lock.yaml (e.g. pin X -> Y) without re-running apm install -> drift would otherwise diff new lockfile against stale cache and report misleading findings.
2. Shared CI runner reuses apm_modules/ across builds where the lockfile changed between jobs.

LockfileBuilder syncs markers unconditionally (even when the lockfile YAML is unchanged AND when no install happens), so existing users self-heal on their next apm install. Threat model is documented in cache_pin.py -- this is stale-cache detection, NOT cryptographic integrity. Active-tampering defense (content-addressed hashes / signatures) is deferred.

Proof of integration test coverage

76 drift tests (was 74 prior to follow-ups; +14 unit cache_pin + new integration test):

uv run pytest tests/unit/install/test_drift.py \
              tests/unit/install/test_cache_pin.py \
              tests/integration/test_drift_check.py \
              tests/integration/test_drift_check_e2e.py
============== 76 passed in 3.71s ==============

Plus the broader local slice ran clean: tests/unit/install/ tests/unit/policy/ tests/unit/utils/ + drift integration -> 1142 passed, 17 subtests passed.

Coverage of past + present drift hazards

Lint

uv run --extra dev ruff check src/ tests/   -> All checks passed!
uv run --extra dev ruff format --check src/ tests/   -> 681 files already formatted

APM Review Panel: ship_with_followups

PR #1137 ships default-on integration drift detection in apm audit, eliminating bespoke CI bash glue and closing the gap between what apm.yml declares and what actually lives in apm_modules.

cc @danielmeppiel @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

The panel converges strongly: 77 tests, 21 scenario-evidence rows, and full E2E coverage make this one of the best-instrumented PRs in the project's history. No panelist found a correctness regression or security bypass. The two highest-signal gaps identified are tightly coupled: the _ReadOnlyProjectGuard in guards.py is defined but never wired into run_replay(), meaning the defense-in-depth no-write contract is unwired dead code; and CacheMissError raised during drift replay in bare apm audit is silently swallowed, giving the user zero feedback. Both concern the same promise -- that drift replay is safe and observable. These should be addressed as a paired follow-up, not a blocker, because the primary protection (_assert_scratch_bound) is in place and the E2E tests confirm the happy path.

The supply-chain-security finding on resolved_commit None silently skipping cache-pin verification for remote deps is the third-highest signal item, carrying a secure-by-default tag on an outcome: missing evidence row. Per the CEO evidence-weighting rules, a missing test on a secure-by-default surface inherits near-blocking weight even when the persona filed it as recommended. This should be the first follow-up issue filed post-merge. The doc-writer's findings on stale '7 baseline checks' copy in ci-cd.md, governance-guide.md, and security.md are straightforward and should be bundled into the same follow-up PR as the CHANGELOG link fix.

The oss-growth-hacker is correct that the before/after CI gate narrative is the strongest launch asset this project has shipped in recent memory. The CHANGELOG entry and drift-detection guide need a light rewrite pass before this becomes release-note source material -- but that is a post-merge content task, not a gate. Auth-expert is inactive and in full agreement: no auth surface was touched.

Aligned with: Secure by default -- drift runs by default; the scratch-bound guard and cache-pin verification enforce the no-mutation contract, though _ReadOnlyProjectGuard and the resolved_commit None silent-skip both need follow-up. Governed by policy -- apm audit --ci now gates on drift as well as lockfile consistency; the stale '7 baseline checks' copy must be updated. Pragmatic as npm -- the 5-line CI bash collapses to a single apm audit invocation; this is the pragmatic payoff the feature was designed to deliver.

Growth signal. The before/after CI gate narrative -- 5 lines of bash becoming one apm audit invocation -- is a screenshot-ready launch asset. To convert that asset into actual adoption signal, the drift-detection guide needs a '## Try it now' copy-paste block and the CHANGELOG entry needs to lead with the user promise ('no bash glue needed') before the flag semantics. Both are 10-minute edits that compound the PR's reach significantly.

Panel summary

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

1. [Supply Chain Security Expert] Remote deps with resolved_commit=None silently skip cache-pin verification; add a CacheMissError or visible warning for this case, plus a unit test proving the behavior. -- outcome:missing on a secure-by-default surface inherits near-blocking weight per CEO evidence rules; this is the highest-risk silent fail-open in the PR.
2. [Python Architect] Wire _ReadOnlyProjectGuard into run_replay() -- it is currently defined in guards.py but never imported or called. -- The defense-in-depth no-write contract is dead code; the module docstring explicitly describes it as the intended wrapping pattern for run_replay().
3. [DevX UX Expert] Emit a stderr message when CacheMissError is swallowed in bare apm audit so users know drift was attempted and why it failed. -- Zero feedback on a stale-cache failure violates the failure-mode principle; confirmed by both devx-ux and cli-logging-expert independently.
4. [Doc Writer] Update ci-cd.md, governance-guide.md, and security.md to replace '7 baseline checks' with the new default-on drift count, and fix the CHANGELOG relative-path link. -- Public doc surfaces understate shipped behavior; governance and security docs are the first place enterprise evaluators look.
5. [OSS Growth Hacker] Rewrite the CHANGELOG entry to lead with the user promise, add a 'Try it now' block to the drift-detection guide, and add a section heading to the before/after CI comparison. -- The strongest launch asset in this PR is currently buried mid-page; a 10-minute edit multiplies reach before the release note is cut.

Architecture

classDiagram
    direction TB
    class audit_command {
        <<EntryPoint>>
        +--ci bool
        +--no-drift bool
    }
    class ReplayConfig {
        <<ValueObject>>
        +project_root Path
        +lockfile_path Path
        +targets frozenset
        +cache_only bool
    }
    class DriftFinding {
        <<ValueObject>>
        +path str
        +kind str
        +package str
        +inline_diff str
    }
    class CheckLogger {
        +replay_start()
        +diff_start()
        +replay_complete(n int)
        +clean()
        +findings(n int)
    }
    class _ReadOnlyProjectGuard {
        <<ContextManager>>
        +project_root Path
        +protected_roots list
        +__enter__()
        +__exit__()
    }
    class CacheMissError {
        <<Exception>>
    }
    class CachePinError {
        <<Exception>>
    }
    class run_replay {
        <<IOBoundary>>
        +config ReplayConfig
        +logger CheckLogger
    }
    class diff_scratch_against_project {
        <<Pure>>
        +scratch_root Path
        +project_root Path
    }
    class verify_marker {
        <<IOBoundary>>
    }
    class write_marker {
        <<IOBoundary>>
    }
    note for CheckLogger "Subclass pattern: redirects emit() to stderr so JSON/SARIF stdout stays clean"
    note for _ReadOnlyProjectGuard "Defined in guards.py; NOT wired into run_replay() -- dead code gap (follow-up #2)"
    note for run_replay "Replay Engine: cache-only materialization into scratch_root via integrate_package_primitives"
    run_replay ..> ReplayConfig : reads
    run_replay ..> CheckLogger : logs via
    run_replay ..> verify_marker : stale-cache guard
    run_replay ..> CacheMissError : raises
    run_replay ..> diff_scratch_against_project : calls
    diff_scratch_against_project ..> DriftFinding : returns list
    verify_marker ..> CachePinError : raises on mismatch
    _ReadOnlyProjectGuard ..> CacheMissError : raises
    audit_command ..> run_replay : invokes via _check_drift
    class ReplayConfig:::touched
    class DriftFinding:::touched
    class CacheMissError:::touched
    class CachePinError:::touched
    class CheckLogger:::touched
    class _ReadOnlyProjectGuard:::touched
    class run_replay:::touched
    class diff_scratch_against_project:::touched
    class verify_marker:::touched
    class write_marker:::touched
    classDef touched fill:#fff3b0,stroke:#d47600

flowchart TD
    A([apm audit]) --> B{--ci?}
    B -->|yes| C["_audit_ci_gate()\naudit.py:395"]
    B -->|no| D["_audit_content_scan()\naudit.py:552"]

    C --> C1["run_baseline_checks()\npolicy/ci_checks.py"]
    C --> C2{not --no-drift\nand apm.yml?}
    C2 -->|yes| DR["_check_drift()\npolicy/ci_checks.py"]
    C2 -->|no| C3["[stderr] drift skipped"]

    D --> D1["[FS] scan_lockfile_packages()"]
    D --> D2{not --no-drift and\napm.yml and no --file/--strip?}
    D2 -->|yes| DR
    D2 -->|no| D3["[stderr] drift skipped"]

    DR --> RP["run_replay(ReplayConfig)\ndrift.py:374"]
    RP --> RP1["[FS] _make_scratch_root()\ntempfile.mkdtemp + atexit.register"]
    RP --> RP2["_assert_scratch_bound()\npoint-in-time only"]
    RP --> RP3{for each lock_dep\nin LockFile}
    RP3 --> RP4["[FS] _materialize_install_path()\ndrift.py:198"]
    RP4 --> RP5["[FS] verify_marker(candidate, commit)\ncache_pin.py -- CachePinError->CacheMissError"]
    RP5 --> RP6["[FS] integrate_package_primitives()\nservices.py scratch_root=scratch"]
    RP6 --> RP3
    RP3 -->|all done| DIFF["diff_scratch_against_project()\ndrift.py:544"]
    DIFF --> FIND["list[DriftFinding]\nmodified / unintegrated / orphaned"]

    FIND --> EC{--ci mode?}
    EC -->|yes| EXIT1(["sys.exit 0 or 1\ndrift escalates in --ci"])
    EC -->|no| EXIT0(["sys.exit 0\ndrift advisory only"])

sequenceDiagram
    actor User
    participant CLI as audit.py
    participant DriftChk as ci_checks._check_drift
    participant Replay as drift.run_replay
    participant Pin as cache_pin.verify_marker
    participant Svc as services.integrate_package_primitives
    participant Diff as drift.diff_scratch_against_project

    User->>CLI: apm audit [--ci] [--no-drift]
    CLI->>DriftChk: _check_drift(project_root, lockfile, cache_only=True)
    DriftChk->>Replay: run_replay(ReplayConfig)
    Replay->>Replay: _make_scratch_root() -- tempfile.mkdtemp
    Replay->>Replay: _assert_scratch_bound() -- point-in-time check
    loop for each lock_dep
        Replay->>Pin: verify_marker(install_path, resolved_commit)
        alt marker ok
            Pin-->>Replay: ok
        else CachePinError
            Pin-->>Replay: raise CachePinError
            Replay-->>DriftChk: raise CacheMissError
        end
        Replay->>Svc: integrate_package_primitives(scratch_root=scratch)
        Svc-->>Replay: files written to scratch only
    end
    Replay-->>DriftChk: scratch_root Path
    DriftChk->>Diff: diff_scratch_against_project(scratch, project, lockfile)
    Diff-->>DriftChk: list[DriftFinding]
    DriftChk-->>CLI: (CheckResult, drift_findings)
    alt --ci mode
        CLI->>User: render + sys.exit(1) if drift
    else bare apm audit
        CLI->>User: render (advisory) + sys.exit(0)
    end

Recommendation

Merge now. The PR is well-tested, the primary safety guard is in place, and no panelist found a blocking defect. File three follow-up issues immediately post-merge: (1) wire _ReadOnlyProjectGuard + emit stderr on CacheMissError swallow (paired, same PR); (2) add resolved_commit=None warning/error with a secure-by-default unit test; (3) doc pass for stale check-count copy and CHANGELOG link. Track the growth-hacker content edits alongside the doc pass -- they are cheap and the launch window is now.

_{This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.}

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by PR Review Panel for issue #1137 · ● 5.8M · ◷

Acknowledging the follow-up batch from the panel synthesis (#issuecomment-4377781459). Working through these in disciplined order:

1. C1 Supply Chain (highest-risk): add CacheMissError/warning for remote deps with resolved_commit=None + unit test
2. C2 Python Architect: wire _ReadOnlyProjectGuard into run_replay()
3. C3 DevX UX + CLI Logging: stderr message when CacheMissError is swallowed in bare apm audit
4. C4 Doc Writer: update ci-cd.md / governance-guide.md / security.md baseline-check counts + CHANGELOG link fix
5. C5 OSS Growth: CHANGELOG user-promise lead, "Try it now" block, before/after section heading

Each will be implemented via the corresponding specialist agent (with test-coverage cross-validation on C1–C3). Posting progress as commits land.

(read-only)

Panel follow-ups C1-C5 addressed (commit 60bf38a)

All five items from the panel review are implemented per the specialist guidance, with cross-validation across the relevant areas.

C1 -- Supply-chain: fail closed on unpinned remote deps

Specialist: supply-chain-security
Why it matters: A remote dep with resolved_commit=None (lockfile from older APM, branch-tracked dep, etc.) cannot have a cache-pin marker written -- so cache-freshness verification was being silently skipped. That's a fail-open on a secure-by-default surface.

Changes:

• cache_pin.find_unpinned_remote_deps() -- new exported helper.
• cache_pin.sync_markers_for_lockfile -- emits [!] stderr warning enumerating affected dep names.
• drift._materialize_install_path -- raises CacheMissError for unpinned remote deps before scratch-deploy. Local deps and pinned remotes unaffected.

Tests: test_sync_markers_warns_on_remote_unpinned_dep, test_find_unpinned_remote_deps_excludes_local_and_pinned, test_materialize_unpinned_remote_dep_raises_cache_miss, test_materialize_local_dep_without_commit_does_not_raise.

C2 -- Architecture: wire _ReadOnlyProjectGuard into run_replay

Specialist: python-architect
Why it matters: The defense-in-depth no-write contract was dead code -- guards.py defined the guard but run_replay never wrapped its loop with it.

Changes:

• run_replay() now wraps the deps-loop in _ReadOnlyProjectGuard(project_root, [*sorted(governed), "apm.lock.yaml", "AGENTS.md"]). Snapshots (mtime_ns, size) per file under protected subpaths and raises ProtectedPathMutationError on any mutation.
• apm_modules/ and the scratch root remain mutable (legitimate cache writes / scratch deploys).

Test: test_run_replay_wraps_loop_with_readonly_guard -- monkeypatches an integrator to write into a governed dir and asserts ProtectedPathMutationError is raised.

C3 -- DevX UX + cli-logging: stderr message on swallowed CacheMissError

Specialists: devx-ux + cli-logging-expert (cross-validation per panel CEO)
Why it matters: Bare apm audit was silently returning no drift findings when the cache was stale -- zero feedback violated the failure-mode principle.

Changes: audit._audit_content_scan -- after _check_drift returns, when drift_failed and not drift_findings, emit [!] drift check could not run: <reason> on stderr (stdout payload unchanged for JSON consumers). Covers cache miss, missing lockfile, cache-pin error.

Test: test_e10_bare_audit_surfaces_cache_miss_on_stderr -- monkeypatches apm_cli.install.drift.run_replay to raise CacheMissError, asserts stderr contains drift check could not run and cache miss, asserts stdout JSON still parses.

C4 -- Docs: baseline-check count + CHANGELOG link

Specialist: doc-writer
Why it matters: Public doc surfaces understated shipped behavior. Enterprise evaluators read governance + security first.

Changes:

• enterprise/governance-guide.md (3 locations), integrations/ci-cd.md (2 locations), reference/cli-commands.md (1 location): "7 baseline checks" -> "7 baseline checks plus integration drift detection" (or equivalent framing).
• CHANGELOG.md: drift-detection link rewritten to canonical doc-site URL (relative path didn't render on GitHub or the doc site).

C5 -- OSS Growth: user-promise framing

Specialist: oss-growth-hacker
Why it matters: The strongest launch asset (drift-as-default) was buried mid-CHANGELOG and the docs page led with mechanism instead of outcome.

Changes:

• CHANGELOG.md drift entry now leads with "apm audit now catches forgotten installs and hand-edits by default." before the mechanism description.
• docs/.../guides/drift-detection.md:
  • Try it now block at the top with cd <project> && apm audit and a quick guide to first-run results.
  • Before/after CI comparison promoted to its own subsection (### Before vs after: the legacy bash workaround) with explicit framing that apm audit --ci catches three classes of drift the bash workaround missed (unintegrated, orphaned, modified).

Verification

• uv run --extra dev ruff check src/ tests/ -- silent
• uv run --extra dev ruff format --check src/ tests/ -- silent (681 files)
• uv run pytest tests/unit -q -- 7621 passed in 81.94s
• uv run pytest tests/unit/install/ tests/integration/test_drift_check.py -x -q -- 603 passed in 6.36s

Ready for re-review.